<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>智能地址解析 - API文档</title>
    <link rel="icon" href="{{ url_for('static', filename='favicon.ico') }}">
    <style>
        body {
            font-family: sans-serif;
            margin: 0;
            padding: 0;
            background-color: #f8f9fa;
            color: #333;
            line-height: 1.6;
        }
        .container {
            max-width: 1000px;
            margin: 40px auto;
            padding: 30px;
            background-color: #fff;
            border-radius: 8px;
            box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
        }
        header {
            display: flex;
            justify-content: space-between;
            align-items: center;
            margin-bottom: 30px;
            border-bottom: 1px solid #eee;
            padding-bottom: 20px;
        }
        .back-link {
            color: #007bff;
            text-decoration: none;
            display: inline-flex;
            align-items: center;
        }
        .back-link:hover {
            text-decoration: underline;
        }
        h1 {
            color: #007bff;
            margin-bottom: 20px;
        }
        h2 {
            color: #555;
            margin-top: 40px;
            margin-bottom: 15px;
            padding-bottom: 8px;
            border-bottom: 1px solid #eee;
        }
        h3 {
            color: #007bff;
            margin-top: 25px;
        }
        pre {
            background-color: #282c34;
            color: #abb2bf;
            padding: 15px;
            border-radius: 4px;
            overflow-x: auto;
            font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
            font-size: 0.95rem;
        }
        code {
            background-color: #f1f1f1;
            padding: 2px 5px;
            border-radius: 3px;
            font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
            font-size: 0.9em;
        }
        .endpoint {
            background-color: #e9ecef;
            padding: 15px;
            border-radius: 4px;
            margin: 15px 0;
            border-left: 4px solid #007bff;
        }
        .method {
            color: #fff;
            background-color: #28a745;
            padding: 4px 8px;
            border-radius: 4px;
            display: inline-block;
            font-size: 0.8rem;
            font-weight: bold;
        }
        .method.post {
            background-color: #007bff;
        }
        .method.get {
            background-color: #28a745;
        }
        table {
            width: 100%;
            border-collapse: collapse;
            margin: 20px 0;
        }
        th, td {
            padding: 12px 15px;
            text-align: left;
            border-bottom: 1px solid #eee;
        }
        th {
            background-color: #f8f9fa;
            font-weight: bold;
        }
        tr:hover {
            background-color: #f8f9fa;
        }
        .parameter-required {
            color: #dc3545;
            font-weight: bold;
        }
        .tab {
            overflow: hidden;
            border: 1px solid #ccc;
            background-color: #f1f1f1;
            border-radius: 4px 4px 0 0;
        }
        .tab button {
            background-color: inherit;
            float: left;
            border: none;
            outline: none;
            cursor: pointer;
            padding: 14px 16px;
            transition: 0.3s;
            font-size: 0.9rem;
        }
        .tab button:hover {
            background-color: #ddd;
        }
        .tab button.active {
            background-color: #007bff;
            color: white;
        }
        .tabcontent {
            display: none;
            padding: 15px;
            border: 1px solid #ccc;
            border-top: none;
            border-radius: 0 0 4px 4px;
            animation: fadeEffect 1s;
        }
        @keyframes fadeEffect {
            from {opacity: 0;}
            to {opacity: 1;}
        }
    </style>
</head>
<body>
    <div class="container">
        <header>
            <h1>智能地址解析 API 文档</h1>
            <a href="{{ url_for('index') }}" class="back-link">← 返回首页</a>
        </header>

        <section>
            <p>智能地址解析API是一个RESTful服务，可以将非结构化的中文地址信息解析为结构化的JSON数据。本文档详细介绍了API的使用方法、认证方式和请求参数。</p>
        </section>

        <section>
            <h2>认证方式</h2>
            <p>所有API接口调用需要通过API密钥认证（除了<code>/api/info</code>接口）。认证方式有三种：</p>

            <h3>1. 请求头认证（推荐）</h3>
            <pre><code>X-API-Key: YOUR_API_KEY</code></pre>

            <h3>2. URL参数认证</h3>
            <pre><code>/api/parse?api_key=YOUR_API_KEY</code></pre>

            <h3>3. 请求体认证</h3>
            <pre><code>{
  "api_key": "YOUR_API_KEY",
  "address": "..."
}</code></pre>
        </section>

        <section>
            <h2>API端点</h2>

            <div class="endpoint">
                <span class="method post">POST</span> <code>/api/parse</code>
                <p>解析非结构化中文地址信息为结构化JSON数据。</p>
                
                <h3>请求参数</h3>
                <table>
                    <tr>
                        <th>参数名</th>
                        <th>类型</th>
                        <th>必填</th>
                        <th>描述</th>
                    </tr>
                    <tr>
                        <td>address</td>
                        <td>String</td>
                        <td><span class="parameter-required">是</span></td>
                        <td>待解析的地址文本</td>
                    </tr>
                    <tr>
                        <td>api_key</td>
                        <td>String</td>
                        <td>否</td>
                        <td>API密钥(如果未通过请求头或URL参数提供)</td>
                    </tr>
                </table>

                <h3>请求示例</h3>
                <div class="tab">
                    <button class="tablinks active" onclick="openTab(event, 'curl')">curl</button>
                    <button class="tablinks" onclick="openTab(event, 'python')">Python</button>
                    <button class="tablinks" onclick="openTab(event, 'javascript')">JavaScript</button>
                </div>

                <div id="curl" class="tabcontent" style="display: block;">
<pre><code>curl -X POST "http://localhost:5000/api/parse" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "address": "广东省深圳市南山区粤海街道科技南十二路 中科纳能大厦 A座 3楼 张三 13800138000 0755-12345678"
  }'</code></pre>
                </div>

                <div id="python" class="tabcontent">
<pre><code>import requests
import json

url = "http://localhost:5000/api/parse"
headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}
data = {
    "address": "广东省深圳市南山区粤海街道科技南十二路 中科纳能大厦 A座 3楼 张三 13800138000 0755-12345678"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(json.dumps(result, indent=2, ensure_ascii=False))</code></pre>
                </div>

                <div id="javascript" class="tabcontent">
<pre><code>// 使用fetch API
const url = 'http://localhost:5000/api/parse';
const headers = {
  'Content-Type': 'application/json',
  'X-API-Key': 'YOUR_API_KEY'
};
const data = {
  address: '广东省深圳市南山区粤海街道科技南十二路 中科纳能大厦 A座 3楼 张三 13800138000 0755-12345678'
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.error('Error:', error));</code></pre>
                </div>

                <h3>响应示例</h3>
                <pre><code>{
  "province": "广东省",
  "city": "深圳市",
  "district": "南山区",
  "street": "粤海街道",
  "address_detail": "科技南十二路 中科纳能大厦 A座 3楼",
  "name": "张三",
  "mobile": "13800138000",
  "telephone": "0755-12345678"
}</code></pre>
            </div>

            <div class="endpoint">
                <span class="method get">GET</span> <code>/api/info</code>
                <p>获取API信息，不需要认证。</p>

                <h3>请求示例</h3>
                <pre><code>curl -X GET "http://localhost:5000/api/info"</code></pre>

                <h3>响应示例</h3>
                <pre><code>{
  "name": "智能地址解析API",
  "version": "1.0",
  "description": "智能解析中文地址信息为结构化数据",
  "authentication": {
    "method": "API Key",
    "header": "X-API-Key"
  }
}</code></pre>
            </div>

            <div class="endpoint">
                <span class="method get">GET</span> <code>/api/generate-key</code>
                <p>生成API密钥，仅在开发环境可用。</p>

                <h3>请求示例</h3>
                <pre><code>curl -X GET "http://localhost:5000/api/generate-key"</code></pre>

                <h3>响应示例</h3>
                <pre><code>{
  "message": "新API密钥已生成",
  "api_key": "生成的新密钥",
  "note": "此密钥仅在本次服务运行期间有效..."
}</code></pre>
            </div>
        </section>

        <section>
            <h2>错误处理</h2>
            <p>当API请求失败时，返回相应的HTTP状态码和错误信息：</p>
            <table>
                <tr>
                    <th>状态码</th>
                    <th>错误类型</th>
                    <th>描述</th>
                </tr>
                <tr>
                    <td>400</td>
                    <td>请求错误</td>
                    <td>请求参数缺失或格式错误</td>
                </tr>
                <tr>
                    <td>401</td>
                    <td>认证失败</td>
                    <td>API密钥无效或缺失</td>
                </tr>
                <tr>
                    <td>429</td>
                    <td>请求过多</td>
                    <td>超过API调用频率限制</td>
                </tr>
                <tr>
                    <td>500</td>
                    <td>服务器错误</td>
                    <td>服务器内部错误或解析失败</td>
                </tr>
            </table>

            <h3>错误响应示例</h3>
            <pre><code>{
  "error": "具体的错误信息..."
}</code></pre>
        </section>
    </div>

    <script>
        function openTab(evt, tabName) {
            var i, tabcontent, tablinks;
            
            tabcontent = document.getElementsByClassName("tabcontent");
            for (i = 0; i < tabcontent.length; i++) {
                tabcontent[i].style.display = "none";
            }
            
            tablinks = document.getElementsByClassName("tablinks");
            for (i = 0; i < tablinks.length; i++) {
                tablinks[i].className = tablinks[i].className.replace(" active", "");
            }
            
            document.getElementById(tabName).style.display = "block";
            evt.currentTarget.className += " active";
        }
    </script>
</body>
</html> 